// ExceptionHandler can write a minidump file when an exception occurs,
// or when WriteMinidump() is called explicitly by your program.
//
// To have the exception handler write minidumps when an uncaught exception
// (crash) occurs, you should create an instance early in the execution
// of your program, and keep it around for the entire time you want to
// have crash handling active (typically, until shutdown).
//
// If you want to write minidumps without installing the exception handler,
// you can create an ExceptionHandler with install_handler set to false,
// then call WriteMinidump.  You can also use this technique if you want to
// use different minidump callbacks for different call sites.
//
// In either case, a callback function is called when a minidump is written,
// which receives the unqiue id of the minidump.  The caller can use this
// id to collect and write additional application state, and to launch an
// external crash-reporting application.
//
// It is important that creation and destruction of ExceptionHandler objects
// be nested cleanly, when using install_handler = true.
// Avoid the following pattern:
//   ExceptionHandler *e = new ExceptionHandler(...);
//   ExceptionHandler *f = new ExceptionHandler(...);
//   delete e;
// This will put the exception filter stack into an inconsistent state.

#ifndef CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__
#define CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__

#include <stdlib.h>
#include <Windows.h>
#include <DbgHelp.h>
#include <Rpc.h>

#pragma warning(push)
// Disable exception handler warnings.
#pragma warning(disable: 4530)

#include <string>
#include <vector>

#include "../base/scoped_ptr.h"
#include "longkey_breakpad\common\minidump_format.h"
#include "client/windows/crash_generation/crash_generation_client.h"

namespace longkey_breakpad
{
	using std::vector;
	using std::wstring;

	class ExceptionHandler
	{
	public:
		// A callback function to run before Breakpad performs any substantial
		// processing of an exception.  A FilterCallback is called before writing
		// a minidump.  context is the parameter supplied by the user as
		// callback_context when the handler was created.  exinfo points to the
		// exception record, if any; assertion points to assertion information,
		// if any.
		//
		// If a FilterCallback returns true, Breakpad will continue processing,
		// attempting to write a minidump.  If a FilterCallback returns false, Breakpad
		// will immediately report the exception as unhandled without writing a
		// minidump, allowing another handler the opportunity to handle it.
		typedef bool (*FilterCallback)(void* context, EXCEPTION_POINTERS* exinfo,
			MDRawAssertionInfo* assertion);

		// A callback function to run after the minidump has been written.
		// minidump_id is a unique id for the dump, so the minidump
		// file is <dump_path>\<minidump_id>.dmp.  context is the parameter supplied
		// by the user as callback_context when the handler was created.  exinfo
		// points to the exception record, or NULL if no exception occurred.
		// succeeded indicates whether a minidump file was successfully written.
		// assertion points to information about an assertion if the handler was
		// invoked by an assertion.
		//
		// If an exception occurred and the callback returns true, Breakpad will treat
		// the exception as fully-handled, suppressing any other handlers from being
		// notified of the exception.  If the callback returns false, Breakpad will
		// treat the exception as unhandled, and allow another handler to handle it.
		// If there are no other handlers, Breakpad will report the exception to the
		// system as unhandled, allowing a debugger or native crash dialog the
		// opportunity to handle the exception.  Most callback implementations
		// should normally return the value of |succeeded|, or when they wish to
		// not report an exception of handled, false.  Callbacks will rarely want to
		// return true directly (unless |succeeded| is true).
		//
		// For out-of-process dump generation, dump path and minidump ID will always
		// be NULL. In case of out-of-process dump generation, the dump path and
		// minidump id are controlled by the server process and are not communicated
		// back to the crashing process.
		typedef bool (*MinidumpCallback)(const wchar_t* dump_path,
			const wchar_t* minidump_id,
			void* context,
			EXCEPTION_POINTERS* exinfo,
			MDRawAssertionInfo* assertion,
			bool succeeded);

		// HandlerType specifies which types of handlers should be installed, if
		// any.  Use HANDLER_NONE for an ExceptionHandler that remains idle,
		// without catching any failures on its own.  This type of handler may
		// still be triggered by calling WriteMinidump.  Otherwise, use a
		// combination of the other HANDLER_ values, or HANDLER_ALL to install
		// all handlers.
		enum HandlerType {
			HANDLER_NONE = 0,
			HANDLER_EXCEPTION = 1 << 0,          // SetUnhandledExceptionFilter
			HANDLER_INVALID_PARAMETER = 1 << 1,  // _set_invalid_parameter_handler
			HANDLER_PURECALL = 1 << 2,           // _set_purecall_handler
			HANDLER_ALL = HANDLER_EXCEPTION |
			HANDLER_INVALID_PARAMETER |
			HANDLER_PURECALL
		};

		// Creates a new ExceptionHandler instance to handle writing minidumps.
		// Before writing a minidump, the optional filter callback will be called.
		// Its return value determines whether or not Breakpad should write a
		// minidump.  Minidump files will be written to dump_path, and the optional
		// callback is called after writing the dump file, as described above.
		// handler_types specifies the types of handlers that should be installed.
		ExceptionHandler(const wstring& dump_path,
			FilterCallback filter,
			MinidumpCallback callback,
			void* callback_context,
			int handler_types);

		// Creates a new ExcetpionHandler instance that can attempt to perform
		// out-of-process dump generation if pipe_name is not NULL. If pipe_name is
		// NULL, or if out-of-process dump generation registration step fails,
		// in-process dump generation will be used. This also allows specifying
		// the dump type to generate.
		ExceptionHandler(const wstring& dump_path,
			FilterCallback filter,
			MinidumpCallback callback,
			void* callback_context,
			int handler_types,
			MINIDUMP_TYPE dump_type,
			const wchar_t* pipe_name,
			const CustomClientInfo* custom_info);

		~ExceptionHandler();

		// Get and set the minidump path.
		wstring dump_path() const { return dump_path_; }
		void set_dump_path(const wstring &dump_path) {
			dump_path_ = dump_path;
			dump_path_c_ = dump_path_.c_str();
			UpdateNextID();  // Necessary to put dump_path_ in next_minidump_path_.
		}

		// Writes a minidump immediately.  This can be used to capture the
		// execution state independently of a crash.  Returns true on success.
		bool WriteMinidump();

		// Writes a minidump immediately, with the user-supplied exception
		// information.
		bool WriteMinidumpForException(EXCEPTION_POINTERS* exinfo);

		// Convenience form of WriteMinidump which does not require an
		// ExceptionHandler instance.
		static bool WriteMinidump(const wstring &dump_path,
			MinidumpCallback callback, void* callback_context);

		// Get the thread ID of the thread requesting the dump (either the exception
		// thread or any other thread that called WriteMinidump directly).  This
		// may be useful if you want to include additional thread state in your
		// dumps.
		DWORD get_requesting_thread_id() const { return requesting_thread_id_; }

		// Controls behavior of EXCEPTION_BREAKPOINT and EXCEPTION_SINGLE_STEP.
		bool get_handle_debug_exceptions() const { return handle_debug_exceptions_; }
		void set_handle_debug_exceptions(bool handle_debug_exceptions) {
			handle_debug_exceptions_ = handle_debug_exceptions;
		}

		// Returns whether out-of-process dump generation is used or not.
		bool IsOutOfProcess() const { return crash_generation_client_.get() != NULL; }

	private:
		friend class AutoExceptionHandler;

		// Initializes the instance with given values.
		void Initialize(const wstring& dump_path,
			FilterCallback filter,
			MinidumpCallback callback,
			void* callback_context,
			int handler_types,
			MINIDUMP_TYPE dump_type,
			const wchar_t* pipe_name,
			const CustomClientInfo* custom_info);

		// Function pointer type for MiniDumpWriteDump, which is looked up
		// dynamically.
		typedef BOOL (WINAPI *MiniDumpWriteDump_type)(
			HANDLE hProcess,
			DWORD dwPid,
			HANDLE hFile,
			MINIDUMP_TYPE DumpType,
			CONST PMINIDUMP_EXCEPTION_INFORMATION ExceptionParam,
			CONST PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam,
			CONST PMINIDUMP_CALLBACK_INFORMATION CallbackParam);

		// Function pointer type for UuidCreate, which is looked up dynamically.
		typedef RPC_STATUS (RPC_ENTRY *UuidCreate_type)(UUID* Uuid);

		// Runs the main loop for the exception handler thread.
		static DWORD WINAPI ExceptionHandlerThreadMain(void* lpParameter);

		// Called on the exception thread when an unhandled exception occurs.
		// Signals the exception handler thread to handle the exception.
		static LONG WINAPI HandleException(EXCEPTION_POINTERS* exinfo);

#if _MSC_VER >= 1400  // MSVC 2005/8
		// This function will be called by some CRT functions when they detect
		// that they were passed an invalid parameter.  Note that in _DEBUG builds,
		// the CRT may display an assertion dialog before calling this function,
		// and the function will not be called unless the assertion dialog is
		// dismissed by clicking "Ignore."
		static void HandleInvalidParameter(const wchar_t* expression,
			const wchar_t* function,
			const wchar_t* file,
			unsigned int line,
			uintptr_t reserved);
#endif  // _MSC_VER >= 1400

		// This function will be called by the CRT when a pure virtual
		// function is called.
		static void HandlePureVirtualCall();

		// This is called on the exception thread or on another thread that
		// the user wishes to produce a dump from.  It calls
		// WriteMinidumpWithException on the handler thread, avoiding stack
		// overflows and inconsistent dumps due to writing the dump from
		// the exception thread.  If the dump is requested as a result of an
		// exception, exinfo contains exception information, otherwise, it
		// is NULL.  If the dump is requested as a result of an assertion
		// (such as an invalid parameter being passed to a CRT function),
		// assertion contains data about the assertion, otherwise, it is NULL.
		bool WriteMinidumpOnHandlerThread(EXCEPTION_POINTERS* exinfo,
			MDRawAssertionInfo* assertion);

		// This function does the actual writing of a minidump.  It is called
		// on the handler thread.  requesting_thread_id is the ID of the thread
		// that requested the dump.  If the dump is requested as a result of
		// an exception, exinfo contains exception information, otherwise,
		// it is NULL.
		bool WriteMinidumpWithException(DWORD requesting_thread_id,
			EXCEPTION_POINTERS* exinfo,
			MDRawAssertionInfo* assertion);

		// This function is used as a callback when calling MinidumpWriteDump,
		// in order to add additional memory regions to the dump.
		static BOOL CALLBACK MinidumpWriteDumpCallback(
			PVOID context,
			const PMINIDUMP_CALLBACK_INPUT callback_input,
			PMINIDUMP_CALLBACK_OUTPUT callback_output);

		// Generates a new ID and stores it in next_minidump_id_, and stores the
		// path of the next minidump to be written in next_minidump_path_.
		void UpdateNextID();

		FilterCallback filter_;
		MinidumpCallback callback_;
		void* callback_context_;

		scoped_ptr<CrashGenerationClient> crash_generation_client_;

		// The directory in which a minidump will be written, set by the dump_path
		// argument to the constructor, or set_dump_path.
		wstring dump_path_;

		// The basename of the next minidump to be written, without the extension.
		wstring next_minidump_id_;

		// The full pathname of the next minidump to be written, including the file
		// extension.
		wstring next_minidump_path_;

		// Pointers to C-string representations of the above.  These are set when
		// the above wstring versions are set in order to avoid calling c_str during
		// an exception, as c_str may attempt to allocate heap memory.  These
		// pointers are not owned by the ExceptionHandler object, but their lifetimes
		// should be equivalent to the lifetimes of the associated wstring, provided
		// that the wstrings are not altered.
		const wchar_t* dump_path_c_;
		const wchar_t* next_minidump_id_c_;
		const wchar_t* next_minidump_path_c_;

		HMODULE dbghelp_module_;
		MiniDumpWriteDump_type minidump_write_dump_;
		MINIDUMP_TYPE dump_type_;

		HMODULE rpcrt4_module_;
		UuidCreate_type uuid_create_;

		// Tracks the handler types that were installed according to the
		// handler_types constructor argument.
		int handler_types_;

		// When installed_handler_ is true, previous_filter_ is the unhandled
		// exception filter that was set prior to installing ExceptionHandler as
		// the unhandled exception filter and pointing it to |this|.  NULL indicates
		// that there is no previous unhandled exception filter.
		LPTOP_LEVEL_EXCEPTION_FILTER previous_filter_;

#if _MSC_VER >= 1400  // MSVC 2005/8
		// Beginning in VC 8, the CRT provides an invalid parameter handler that will
		// be called when some CRT functions are passed invalid parameters.  In
		// earlier CRTs, the same conditions would cause unexpected behavior or
		// crashes.
		_invalid_parameter_handler previous_iph_;
#endif  // _MSC_VER >= 1400

		// The CRT allows you to override the default handler for pure
		// virtual function calls.
		_purecall_handler previous_pch_;

		// The exception handler thread.
		HANDLE handler_thread_;

		// True if the exception handler is being destroyed.
		// Starting with MSVC 2005, Visual C has stronger guarantees on volatile vars.
		// It has release semantics on write and acquire semantics on reads.
		// See the msdn documentation.
		volatile bool is_shutdown_;

		// The critical section enforcing the requirement that only one exception be
		// handled by a handler at a time.
		CRITICAL_SECTION handler_critical_section_;

		// Semaphores used to move exception handling between the exception thread
		// and the handler thread.  handler_start_semaphore_ is signalled by the
		// exception thread to wake up the handler thread when an exception occurs.
		// handler_finish_semaphore_ is signalled by the handler thread to wake up
		// the exception thread when handling is complete.
		HANDLE handler_start_semaphore_;
		HANDLE handler_finish_semaphore_;

		// The next 2 fields contain data passed from the requesting thread to
		// the handler thread.

		// The thread ID of the thread requesting the dump (either the exception
		// thread or any other thread that called WriteMinidump directly).
		DWORD requesting_thread_id_;

		// The exception info passed to the exception handler on the exception
		// thread, if an exception occurred.  NULL for user-requested dumps.
		EXCEPTION_POINTERS* exception_info_;

		// If the handler is invoked due to an assertion, this will contain a
		// pointer to the assertion information.  It is NULL at other times.
		MDRawAssertionInfo* assertion_;

		// The return value of the handler, passed from the handler thread back to
		// the requesting thread.
		bool handler_return_value_;

		// If true, the handler will intercept EXCEPTION_BREAKPOINT and
		// EXCEPTION_SINGLE_STEP exceptions.  Leave this false (the default)
		// to not interfere with debuggers.
		bool handle_debug_exceptions_;

		// A stack of ExceptionHandler objects that have installed unhandled
		// exception filters.  This vector is used by HandleException to determine
		// which ExceptionHandler object to route an exception to.  When an
		// ExceptionHandler is created with install_handler true, it will append
		// itself to this list.
		static vector<ExceptionHandler*>* handler_stack_;

		// The index of the ExceptionHandler in handler_stack_ that will handle the
		// next exception.  Note that 0 means the last entry in handler_stack_, 1
		// means the next-to-last entry, and so on.  This is used by HandleException
		// to support multiple stacked Breakpad handlers.
		static LONG handler_stack_index_;

		// handler_stack_critical_section_ guards operations on handler_stack_ and
		// handler_stack_index_. The critical section is initialized by the
		// first instance of the class and destroyed by the last instance of it.
		static CRITICAL_SECTION handler_stack_critical_section_;

		// The number of instances of this class.
		volatile static LONG instance_count_;

		// disallow copy ctor and operator=
		explicit ExceptionHandler(const ExceptionHandler &);
		void operator=(const ExceptionHandler &);
	};
}

#pragma warning(pop)

#endif